Release 10.1A: OpenEdge Development:
Programming Interfaces

Custom audit archiving tools

OpenEdge provides core support for archiving audit data from short-term audit-trail storage to long-term audit-trail storage. The Audit Archiving utility provided with OpenEdge allows you to:

Archive audit data (move selected audit data records and copy other supporting records) from active short-term storage in an OpenEdge RDBMS to long-term storage in the form of audit binary dump (.adb) files.
Calculate and store an HMAC data integrity value along with the archived audit data that can be used to verify that the data has not been tampered with before it is loaded into another OpenEdge RDBMS. (An HMAC is a form of message authentication code that uses a secret key.)
Purge audit data (delete selected audit data records) from the short term storage with or without an archive of the same data.
Load audit data contained in .adb files into an audit-enabled OpenEdge RDBMS.
Run multiple concurrent instances of the utility, which handle record access conflicts through a record locking protocol. This same record locking protocol allows you to run the utility on a live database without the need to take it offline.

For more information on the OpenEdge Audit Archiving utility, see OpenEdge Getting Started: Core Business Services .

Accessing the audit data and supporting tables

You can write your own tools to archive audit data in other ways than are supported by the OpenEdge Audit Archiving utility. For example, where the OpenEdge Audit Archiving utility dumps audit data to .adb files, you might want to move the data directly from the database used for short-term storage directly to a database that you use for long-term storage. For another example, the Audit Archiving utility never deletes the audit archive events generated during the process of archiving the audit data in a given database. You might want your custom audit archiving tool to delete the audit archiving events that are generated in short-term storage during the process of archiving.

Caution: Archiving audit data requires special privileges because it is the only auditing activity that allows audit data to be programmatically created and deleted. Maintain appropriate security for any tool that you build to do audit archiving. For more information, see the "Audit archiving security" section.

The tables for auditing archiving include:

_aud-audit-data — Contains the audit records generated as a result of enabling audit events in an active audit policy. For archiving, you generally move the records in this table from short-term to long-term storage.
_aud-audit-data-value — Optionally, contains the before and after field values for database events that modify fields in one record per modified field. For archiving, you generally move the records in this table from short-term to long-term storage.
_aud-event — Defines the audit events that generate the audit records in _aud-audit-data. For archiving, you generally copy (not move) the records to long-term storage for audit events represented by the generated audit records.
_client-session — Optionally, records information about the client login session, including how the login session was authenticated, in order to support nonrepudiation of the audit data. For archiving, you generally copy (not move) the _client-session records to long-term storage that are associated with the generated audit records you are archiving.
Note: Records for a client session are only available if you specify the option to record client sessions in the database whose short-term audit data you are archiving. For more information on recording client sessions, see the "Generating client login session context" section.
_db-detail — Contains audit data about the database being archived, that is, the database where the audit trail being archived was originally generated. For archiving, you generally copy the _db-detail records to long-term storage that are associated with the generated audit records you are archiving. There can be more than one _db-detail record if you are archiving audit data from more than one audit-enabled database. This provides access to the MAC key (database passkey) used to validate audit data record seals from each database that provides audit data records for archiving. For more information, see the "Audit archiving security" section.

For more information on these tables, see the sections on the audit data tables in OpenEdge Getting Started: Core Business Services .

Handling archiving requirements

The exact archiving requirements for your custom audit archiving utility are largely application dependent. However, there are a few issues that you must consider when writing the code for such a utility:

You must manage any record access conflicts that might arise from archiving a live online database or from running multiple audit archiving utilities concurrently on the same set of databases.
You might have additional security requirements over and above what OpenEdge requires that you want to enforce. For more information, see the "Audit archiving security" section.
You must manage your own encryption and data integrity if you use your own intermediate storage medium, such as XML. For more information, see the sections on cryptography in Chapter 2, " Application Security."
Some fields in audit data records are stored using Base64 representations of binary bytes strings. You can convert between Base64 character strings and binary byte strings using the BASE64-ENCODE and BASE64-DECODE 4GL functions. You can also convert between binary byte strings and strings of hexadecimal character pairs using the HEX-ENCODE and HEX-DECODE 4GL functions. For more information, see the sections on managing cryptographic data in Chapter 2, " Application Security."

Besides any special requirements like these, the archiving procedure generally relies on simple queries of the audit data tables according to your predetermined or user-selectable data selection criteria. Typically, you then write the queried records to your long-term storage in a manner that exactly replicates their content and relationships in the original short-term storage. However, again, your own long-term audit data storage requirements might be different.

Audit archiving security

OpenEdge requires that any user who runs an audit archiving tool, particularly one that deletes and creates audit data records, must have the Audit Data Archiver privilege. You might also authorize users of your own audit archiving utility to have privileged access to the files and directories that constitute your long-term audit data storage or require them to have privileged knowledge of the MAC keys that you use to transport audit data from short-term to long-term storage.

The audit data can be sealed using a MAC key (database passkey), depending on the audit data security level. You can specify this database passkey using the Admin Database Identification menu option in the Data Administration tool or character-mode Data Dictionary. An encrypted form of this value is stored in the _db-detail table for the database. When you dump and later load the archived audit data, you need this value to ensure the integrity of the data.

You can prompt for the database passkey as part of the archiving process and encrypt it in the same form that is used by OpenEdge and stored in the _db-detail table. To encrypt the user-supplied value, pass it to the ENCRYPT-AUDIT-MAC-KEY( ) method on the AUDIT-POLICY system handle. You can then compare this value to the value stored in the _db-detail table.